What Does This Do

Moves TagInterceptor from name-keyed to id-keyed dispatch. This is groundwork for instrumentation setting tags by KnownTags.*_ID constants.

• Intercepted bit in the id. A new Java overlay, tag-conventions-java.yaml, sits next to the language-agnostic conventions. It declares the keys that exist only to be routed (resource.name, error, span.type, manual.keep, sampling.priority, ...) and lists every tag TagInterceptor may route. Each listed tag's id carries KnownTagCodec.INTERCEPTED (bit 1).
• TagInterceptor switches on the tag's serial. A known tag is matched under any of its names, so the *_OTEL_NAME cases are gone. split-by-tags entries resolve to a fixed-size table indexed by serial at construction, so the check is a single load; a name declared per direction (peer.port) covers both directions. Only custom tags are still matched by name.
• DDSpanContext sets by id first. A name setter resolves the id once and then takes the id path. The id setters no longer look up the name to feed the interceptor. Entry paths (builder ledger, prototypes, default tags) route by entry.tagId() and check before boxing.
• nameOf reads a generated NAMES_BY_SERIAL array instead of a switch. It was 491 bytes, "hot method too big" for C2; it's now 23 bytes and inlines.
• Custom tags are built by name, known tags by id. Entry's package-private name factories are custom-only: they skip the registry and assert the name isn't a known tag. Callers that start from a name resolve it once. TagMap.set(String, ...) forwards a known tag to set(long, ...); getAndSet, put, Ledger.set, putAll and the public Entry.create(String, ...) resolve through anyEntryFor and its siblings. A custom tag now pays one registry lookup instead of two: TagMapInsertBenchmark's custom case is 8–12% faster.
• Shared-name ids are rejected on the id paths for now. A tag declared once per direction (peer.port) has two ids but one Datadog name, which keyOf resolves to neither. Until name resolution knows a span's direction (Resolve direction-dependent tag names by the span's kind (otlp - tag registry - phase 3) #12731), a SHARED_NAME id bit marks those ids. TagMap's id-keyed create, get and remove reject them, and the span's id setters ignore them (KnownTagCodec.isKeyableById). The check folds away for a constant id.
• TagMap.internals(): a restricted, trusted path for the tracer core. Its setKnown(...) skips the id validation that set(long, ...) repeats. The span's id setters, which have already checked isKeyableById, use it. Internals is created per call, so escape analysis removes it. A new @Restricted(allowedIn = ...) annotation marks internals(), and gradle/forbiddenApiFilters/instrumentation.txt bans it in instrumentation modules (verified: a call from an instrumentation module fails forbiddenApisMain). Internals is also where the batched setTagsFrom/TagSink writes will go.

Motivation

With a constant id, setTag(KnownTags.X_ID, v) should inline completely and fold away both the interception test and the custom-tag path. That leaves the store. Once the dense store puts the slot coordinate into the id, the store becomes direct too.

C2 inline trees (Zulu 17), steady state:

• setTag(HTTP_ROUTE_ID, ...), not intercepted: every call inlines. The isIntercepted test folds and interceptTag disappears.
• setTag(SPAN_KIND_ID, ...), intercepted: the same, except for one out-of-line call to the interceptTag switch (483 bytes).

Before the nameOf change, both trees made two out-of-line calls into the 491-byte nameOf switch on every set.

Insert cost (TagMapInsertBenchmark, 12 tags per op, C2 on Zulu 17, two runs per side), against the commit before the registry (#12354):

Setting by id is back to pre-registry speed. By name costs about 3 ns per tag for canonicalization (a keyOf hit, then nameOf). Custom tags pay a keyOf miss and 8 bytes per entry; that's a follow-up. The dense store is where ids get ahead of pre-registry.

Span setTag (SetTagBenchmark, C2 on Zulu 17) is about 13.5 ns whichever way the tag is named, against 5.8 ns for a bare TagMap store. The span's uncontended synchronized is most of the difference, which is why it hides the per-tag gain. Batching (setTagsFrom with one lock per batch) and the dense store are the steps that reach it.

Additional Notes

• Stacked on Set known tags by id on TagMap and spans (otlp - tag registry - phase 2) #12715 through a merge commit (Merge set-by-id (#12715) onto master), with a later merge from master for the CODEOWNERS team rename (@DataDog/apm-sdk-capabilities). Review this PR's own, non-merge commits: git log --first-parent --no-merges 7a017a5657..dougqh/id-tag-interceptor. I'll rebase once Set known tags by id on TagMap and spans (otlp - tag registry - phase 2) #12715 lands.
• Drift: the intercepted bit was taken out earlier because it drifted from the interceptor's switch. exactlyTheTagsWithTheInterceptedBitHaveACase runs every known id through the switch and requires a case exactly when the bit is set. Removing error from the overlay makes it fail.
• Fix split-by-tags for tags configured by OpenTelemetry name #12814 (the short-term split-by-tags fix) is superseded by this PR: id matching covers OTel names. Whichever lands second drops withCanonicalNames.
• Unknown and shared-name ids are ignored by the span API, while TagMap's checked id routines throw. The span's guard is KnownTagCodec.isKeyableById: a range check against a generated SERIAL_LIMIT, plus the SHARED_NAME bit, both of which fold away for a constant id.
• interceptTag(long) stays too big for C2 to inline (over FreqInlineSize, 325 bytes of bytecode), on purpose. If it inlined, setTag's standalone compiled code would pick up the profiled handler bodies and grow past InlineSmallCode (2500 bytes), and callers would stop inlining setTag. TagInterceptorInliningTest pins the size. A small, foldable handler switch (dense intercepted serials, constant handlers) was tried and works, but it doesn't fit until the dense store shrinks setTag's store path, so it's deferred to that PR.
• Inlining headroom: at the PR head, the standalone C2 compile of DDSpan.setTag(long, String) is about 2,300 bytes, against the 2,500-byte InlineSmallCode limit for inlining an already compiled method into callers. That margin is worth watching as the set path changes.
• Generator: the tracer overlay is optional input (tracerOverlayFile), and overlay tags join no span type's resolved set.

🤖 Generated with Claude Code